package cz.cuni.mff.ufal.volk.services;

import java.util.List;

import cz.cuni.mff.ufal.volk.Speech;

/**
 * A common speech converter.
 * 
 * @author Bartłomiej Etenkowski
 */
public interface SpeechConverter {
  
  /**
   * Returns the list of all supported source formats.
   * @return the list of all supported source formats
   */
  List<String> sourceFormats();
  
  /**
   * Returns the list of all supported source formats that can be converted into the target
   * format provided as parameter.
   * @param  targetFormat the target format
   * @return the list of supported source formats
   */
  List<String> sourceFormats(String targetFormat);
  
  /**
   * Returns the list of all supported target formats. 
   * @return the list of all supported target formats
   */
  List<String> outputFormats();
  
  /**
   * Returns the list of all supported target formats for the source format
   * provided as parameters.
   * @param sourceFormat the source format
   * @return the list of supported target formats
   */
  List<String> outputFormats(String sourceFormat);

  /**
   * Converts speech in a source format into the desired target format. 
   * 
   * @param  input the input to convert
   * @param  targetFormat the target format
   * @return the speech converted into the requested format
   * 
   * @throws NullPointerException if any of the parameters is {@code null}
   * @throws IllegalArgumentException if the {@code targetFormat}, source format or the pair
   *         of formats is not supported by the converter
   */
  Speech convert(Speech input, String targetFormat) throws IllegalArgumentException;
  
}
